<%@ taglib prefix="s" uri="/struts-tags"%>
<html>
<head>
<link rel="stylesheet" href="css/protocol.css" type="text/css" />
</head>
<body>
<div id="wrapper-header">
<div id="header">
<h2><a title="Go to company home." href="/protocol"><s:property value="model.name"/>
Protocol</a></h2>
<h3>/</h3>
<h3>API Documentation <s:property value="model.version"/></h3>
</div>
</div>

<div id="wrapper-header">
<div id="content"><a name="Overview"></a>
<h1>Overview</h1>
<p></p>
<p></p>
<a name="Introduction"></a>
<h2>Introduction</h2>
<p><a href="<s:property value="model.namespace"/>/"><s:property value="model.name"/></a> has an <a
	href="http://en.wikipedia.org/wiki/API">Application&nbsp;Programming&nbsp;Interface</a>
(API) for anyone to create fun projects with <s:property value="model.name"/>.</p>
<p></p>
<a name="Versioning"></a>
<h3>Versioning</h3>
<p></p>
<p><b> Current version: <s:property value="model.version"/> </b><br />
<a class="WikiLink" id="p-57f4eaa1e1da6a318057f9f39739da4ffdf143fd"
	href="/API+Version+History">Previous Versions</a></p>
<p>The API request URL has a version parameter which ensures
compatibility when a new version of the <s:property value="model.name"/> API is released. If the
version number is omitted from the URL, <s:property value="model.name"/> will assume the latest
version of the API.</p>
<p></p>
<a name="Authentication"></a>
<h3>Authentication</h3>
<p>To access private data or post a note via the <s:property value="model.name"/> API,
developers will need to authenticate the <s:property value="model.name"/> user. There are
currently two methods for authenticating users for the <s:property value="model.name"/> API: Http
Basic Authentication and OAuth.</p>
<p></p>
<a name="RegisteringanApplication"></a>
<h4>Registering an Application</h4>
<p>First, developers must register their application via the <s:property value="model.name"/>
website. It is possible to edit application information at any time, and
the application won't appear in the application directory until
published.</p>
<p>Register your application: <a
	href="<s:property value="model.namespace"/>/apps/new/"><s:property value="model.namespace"/>/apps/new/</a><br />
View all your applications: <a
	href="<s:property value="model.namespace"/>/apps/"><s:property value="model.namespace"/>/apps/</a></p>
<p></p>
<a name="HttpBasicAuthentication"></a>
<h4>Http Basic Authentication</h4>
<p>Developers will need to construct and send the appropriate
authorization header. To construct the header:
<ul>
	<li>append the username and password like username:password</li>
	<li>base-64 encode the username:password</li>

	<li>send the "Authorization" header with the value "Basic x" where
	x is the base-64 encoded username:password</li>
</ul>
See: <a href="http://en.wikipedia.org/wiki/Basic_access_authentication">Http&nbsp;Basic&nbsp;Authentication</a>
</p>
<p>With each Http Basic authenticated request, the parameter <span
	class="box">app_key</span> must also be included. The <span class="box">app_key</span>
is the application key assigned when the application was registered.</p>
<p></p>
<a name="OAuthAuthentication"></a>

<h4>OAuth Authentication</h4>
<p>OAuth is so hot right now and the <s:property value="model.name"/> API has it.</p>
<p><b> request token url: </b><span class="box"><s:property value="model.namespace"/>/oauth/request_token</span><br />
<b> user authorization url: </b><span class="box"><s:property value="model.namespace"/>/oauth/authorize</span><br />
<b> access token url: </b> <span class="box"><s:property value="model.namespace"/>/oauth/access_token</span><br />

<b> signature methods: </b> HMAC-SHA1<br />
<b> request token expiration: </b> 1 day<br />
<b> access token expiration: </b> never</p>
<p>Your <span class="box">oauth_consumer_key</span> and <span
	class="box">oauth_consumer_secret</span> are your application key and
application secret assigned when you registered your application. The <span
	class="box">app_key</span> parameter is not required since each OAuth
request must contain the <span class="box">oauth_consumer_key</span>.</p>
<p>See: <a href="http://oauth.net">OAuth&nbsp;website</a>, <a
	href="http://oauth.net/documentation/">OAuth&nbsp;documentation</a></p>
<p></p>
<a name="AuthenticationHelp"></a>
<h4>Authentication Help</h4>
<p>If you are having trouble with authentication please post a
message to the <a href="http://groups.google.com/group/companyapi">Google&nbsp;Group</a>.</p>
<p></p>
<a name="Pagination"></a>
<h3>Pagination</h3>
<p>It is up to <s:property value="model.name"/> application developers to decide how to
paginate lists of items by using the <span class="box">limit={limit}</span>
and <span class="box">page={page}</span> parameters. The first page is
page 0. For example, if I like 5 friends per page and I want the 3rd
page of friends for <a href="<s:property value="model.namespace"/>/dburka/">Daniel&nbsp;Burka</a>,
I would use: <span class="box"><s:property value="model.namespace"/>/users/dburka/friends.xml?limit=5&page=2</span></p>
<p>If a particular page does not exist, a HTTP 404 error is returned
and applications should handle this gracefully.</p>
<p></p>
<a name="RateLimiting/Throttling"></a>
<h3>Rate Limiting / Throttling</h3>
<p></p>
<p>The API currently has no limit on the number of requests
applications can make. Please be kind to the API so we can keep it that
way and try to use the minimum number of requests to accomplish a task.
If you need help figuring out how to efficiently perform a task, feel
free to ask in the <a href="http://groups.google.com/group/companyapi">Google&nbsp;Group</a>.</p>
<p>Posting notes <b>does</b> have a rate limit per user. Each user
may post <b>20</b> notes every <b>10</b> minutes (average 2 per minute)
and no more than <b>300</b> notes per day. This limit is to prevent
spammers and friend-annoyers.</p>
<p></p>
<a name="JSONCallbackParameter"></a>
<h3>JSON Callback Parameter</h3>
<p>Developers may include an optional JavaScript callback parameter
<span class="box">callback={callback}</span> for JSON requests. The
response will then be wrapped in the callback function. For example if I
include the parameter <span class="box">callback=testFunction</span> the
response will look like <span class="box">testFunction(...);</span></p>
<p>Callback function names must start with a letter and are
restricted to letters, numbers and underscores.</p>
<p></p>
<a name="CrossDomainXML"></a>
<h3>Cross Domain XML</h3>
<p>Adobe Flash applications have permission to access the <s:property value="model.name"/>
API and the cross domain XML file can be found at <a
	href="<s:property value="model.namespace"/>/crossdomain.xml"><s:property value="model.namespace"/>/crossdomain.xml</a></p>
<p></p>
<a name="TryItOut"></a>
<h2>Try It Out</h2>
<p></p>
<p>You can try all the API methods via a web browser or use the
command-line tool, <a href="http://curl.haxx.se/">cURL</a>. You probably
already have cURL. Try getting <a
	href="<s:property value="model.namespace"/>/kevin/">Kevin&nbsp;Rose</a>'s public
profile by typing the following into the command-line:</p>
<p></p>
<table>
	<tr>
		<td>curl <s:property value="model.namespace"/>/users/kevin.xml</td>
	</tr>
</table>
<p>Test out authentication by verifying the authorized user.</p>
<p></p>
<table>
	<tr>
		<td>curl -H "Authorization: basic {encoded}"
		"<s:property value="model.namespace"/>/auth/verify.xml?app_key={app_key}"</td>
	</tr>
</table>
<p></p>
<a name="Help"></a>
<h2>Help</h2>
<p>The easiest way to get help with the <s:property value="model.name"/> API is to check out
our <a href="http://groups.google.com/group/companyapi">Google&nbsp;Group</a>.
Feel free to join and ask questions, suggest improvements, and
collaborate on projects.</p>
<p>Is there something you want from the <s:property value="model.name"/> API that you can't
seem to find? Try posting to the <a
	href="http://groups.google.com/group/companyapi">Google&nbsp;Group</a>
with the information you'd like from the API. More API endpoints WILL be
added to the API depending on input from developers like you.</p>
<p></p>
<a name="APIMethods"></a>


<h1>API Methods</h1>
<p></p>
<p></p>

<s:iterator value="model.topics">
	<a name="<s:property value='name'/>"></a>
	<h2><s:property value='name' /></h2>
	<p></p>
	<p></p>

	<s:iterator value="resources">
		<a name="<s:property value='name'/>"></a>
		<h3><s:property value='name' /></h3>
		<s:iterator value="methods">
			<p><s:property value='description' /><br />
			<b> url: </b><span class="box"><s:property value='namespace' /><s:property value='pattern' /></span><br />

			<b> request methods: </b> <s:property value='verb' /><br />
			<b> authentication: </b> <s:property value='auths' /><br />
			<b> required url parameters: </b>
			<ul>
				<s:iterator value="requiredParameters">
					<li><span class="box"><s:property value="name" /></span>, <s:property value="description" escape="false"/></li>
				</s:iterator>
			</ul>
			<b> optional url parameters: </b>
			<ul>
				<s:iterator value="optionalParameters">
					<li><span class="box"><s:property value="name" /></span>, <s:property value="description" escape="false"/></li>
				</s:iterator>
			</ul>
			<b> notes: </b>
			<ul>
				<s:iterator value="notes">
					<li><s:property escape="false" /></li>
				</s:iterator>
			</ul>
			<b> examples: </b>
			<ul>
				<s:iterator value="examples">
					<li><span class="box"><s:property escape="false" /></span></li>
				</s:iterator>
			</ul>
			</p>
		</s:iterator>
	</s:iterator>
</s:iterator> <a name="APIErrorResponses"></a>
<h2>API Error Responses</h2>
<p></p>
<p>Errors are returned in the same format as the request.</p>
<p>The response contains:
<ul>
	<li><span class="box">status_code</span> HTTP error response code.</li>
	<li><span class="box">message</span> Error message.</li>
	<li><span class="box">request</span> Request url that returned
	this error.</li>

</ul>
The WWW-Authenticate header is returned for any endpoints which require
authentication.
</p>
<p></p>
<a name="<s:property value="model.name"/>Integration"></a>
<h1><s:property value="model.name"/> Integration</h1>
<p></p>
<p></p>
<a name="SendTo<s:property value="model.name"/>"></a>
<h2>Send To <s:property value="model.name"/></h2>
<p>Post content to <s:property value="model.name"/> via a the <s:property value="model.name"/> website with a simple
link.</p>
<p><b> default simple url: </b><span class="box"><s:property value="model.namespace"/>/send/</span></p>
<p></p>
<a name="SendaMessage"></a>
<h3>Send a Message</h3>
<p><b> url: </b><span class="box"><s:property value="model.namespace"/>/send/message/</span><br />
<b> optional url parameters: </b>
<ul>
	<li><span class="box">{note_body}</span> The main text body of the
	note.</li>
	<li><span class="box">{note_to}</span> The recipient(s) of the
	note. Options are <b>public</b>, <b>all</b>, <b>friend_x</b>, or <b>set_x</b>.</li>

</ul>
<b> example link: </b> <span class="box"><s:property value="model.namespace"/>/send/message/?note_body=Hello+world%21&note_to=public</span>
</p>
<p></p>
<a name="SendaLink"></a>
<h3>Send a Link</h3>
<p><b> url: </b><span class="box"><s:property value="model.namespace"/>/send/link/</span><br />
<b> optional url parameters: </b>
<ul>
	<li><span class="box">{url}</span> The full url for the link.</li>
	<li><span class="box">{note_body}</span> The main text body of the
	note.</li>
	<li><span class="box">{note_to}</span> The recipient(s) of the
	note. Options are <b>public</b>, <b>all</b>, <b>friend_x</b>, or <b>set_x</b>.</li>

</ul>
<b> example link: </b> <span class="box"><s:property value="model.namespace"/>/send/link/?url=http%3A%2F%2Fxkcd.com%2F388%2F&note_body=Lemons+are+not+untasty%21</span>
</p>
<p></p>
<a name="SendanEvent"></a>
<h3>Send an Event</h3>
<p><b> url: </b><span class="box"><s:property value="model.namespace"/>/send/event/</span><br />
<b> optional url parameters: </b>
<ul>
	<li><span class="box">{event_name}</span> Name of the event.</li>
	<li><span class="box">{event_location}</span> Location of the
	event.</li>
	<li><span class="box">{event_date}</span> Date of the event in the
	format YYYY-MM-DD. Ex: <span class="box">2008-01-16</span></li>
	<li><span class="box">{event_time}</span> Time of the event in the
	format hh:mm. Ex: <span class="box">20:00</span></li>

	<li><span class="box">{note_body}</span> The main text body of the
	note.</li>
	<li><span class="box">{note_to}</span> The recipient(s) of the
	note. Options are <b>public</b>, <b>all</b>, <b>friend_x</b>, or <b>set_x</b>.</li>
</ul>

<b> example link: </b> <span class="box"><s:property value="model.namespace"/>/send/event/?event_name=Drinking%20at%20Fly%20Bar&event_location=62%20Divisadero%20St,%20San%20Francisco,%20CA&event_date=2008-03-27&event_time=10:00&note_body=Let's%20celebrate%20something.</span>
</p>
<p></p>
<a name="Feeds"></a>
<h2>Feeds</h2>
<p></p>
<a name="NoteFeed"></a>
<h3>Note Feed</h3>
<p>Atom feeds are currently available for all recent public notes as
well as a user's public notes.</p>
<p><b> recent public notes: </b><span class="box"><s:property value="model.namespace"/>/feeds/public/</span><br />
<b> user's notes: </b><span class="box"><s:property value="model.namespace"/>/feeds/public/{username}/</span></p>
<p></p>
<a name="CalendarFeed"></a>
<h3>Calendar Feed</h3>
<p>There's an iCal feed for upcoming, attending, and all public
events. This feed can be used with calendar applications such as Google
calendar.</p>
<p><b> public events: </b><span class="box">webcal://company.exmachina.ch/ical/events/public/</span><br />

<b> my upcoming events: </b><span class="box">webcal://company.exmachina.ch/ical/events/upcoming/{syndication_key}/</span><br />
<b> events I'm attending: </b><span class="box">webcal://company.exmachina.ch/ical/events/attending/{syndication_key}/</span></p>
<p></font><br />
</p>
<!-- google_ad_section_end --> <!--comments--> <!-- google_ad_section_start(weight=ignore) -->
<br style="clear: both" />


</div>
</div>
</body>
</html>
